# Python Virtual Environment Usage

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

This document describes the basic use of Python virtual environments on Quectel Pi H1 and provides recommendations for project dependency management.

# Scope

For Python script development, application debugging, or dependency verification on Quectel Pi H1, it is recommended to create an independent virtual environment for each project.

The main purposes of using a virtual environment are:

- isolating dependency versions between projects;

- preventing third-party packages from affecting the system Python environment;

- simplifying project migration, reproduction, and maintenance;

- reducing differences between development and deployment environments.

# Usage principles

For project management, it is recommended to maintain the virtual environment together with the project directory and to manage dependencies with an explicit dependency file. For long-term maintained applications, avoid installing project-specific packages directly into the system environment.

Recommended practices include:

- using one virtual environment per project;

- keeping the virtual environment directory associated with the project directory;

- freezing dependency versions with files such as `requirements.txt`;

- using the same dependency set across development, testing, and deployment whenever possible.

# Environment setup

First, confirm that `python3` is available on the device:

```bash
python3 --version
```

If the virtual environment module is not installed, run:

```bash
sudo apt update
sudo apt install -y python3-venv
```

# Environment creation

It is recommended to create the virtual environment in the project root directory. A common directory name is `.venv`.

```bash
python3 -m venv .venv
```

After execution, an independent environment directory is created in the current path, containing the interpreter, `pip`, and the package installation location for that environment.

# Environment activation

Activate the environment in the current shell session:

```bash
source .venv/bin/activate
```

After activation, the shell prompt usually shows the environment name as a prefix, indicating that commands are running inside the virtual environment.

This state applies only to the current shell session. If a new terminal is opened, the activation command needs to be run again.

# Dependency installation

After entering the virtual environment, `pip` may be updated first:

```bash
pip install --upgrade pip
```

Then install the required packages:

```bash
pip install <package_name>
```

For example:

```bash
pip install requests pyserial
```

These packages are installed only into the current virtual environment and do not modify the system-wide Python dependencies.

# Dependency freeze and restore

To support project migration and environment reproduction, it is recommended to export the current dependency list after installation:

```bash
pip freeze > requirements.txt
```

On another device or in a recreated environment, first create and activate a virtual environment, then run:

```bash
pip install -r requirements.txt
```

This workflow is suitable for scenarios such as reflashing the development board, migrating a project directory, or deploying the same application to multiple devices.

# Environment deactivation

When the current task is complete, exit the virtual environment with:

```bash
deactivate
```

After deactivation, the shell returns to the system default Python environment.

# Management recommendations

When maintaining Python projects on Quectel Pi H1, the following points are recommended:

- the `.venv` directory is usually excluded from version control;

- `requirements.txt` should be maintained together with the project;

- if package installation fails, first check network access, system time, and build dependencies;

- for projects involving UART, GPIO, I2C, and other hardware interfaces, complete verification inside the virtual environment before preparing deployment steps;

- for deployment, avoid upgrading critical dependencies temporarily if version consistency is required.